home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / rcs5ap1s.lzh / RCS.MS < prev    next >
Text File  |  1991-01-30  |  58KB  |  1,525 lines
  1. .\" Format this file with:
  2. .\" pic file | tbl | troff -ms
  3. .\"
  4. .\" \*s stands for $, and avoids problems when this file is checked in.
  5. .ds s $
  6. .\" PS and PE center pic diagrams. (The corresponding ms-macros may not.)
  7. .de PS
  8. .nr pE (\\n(.lu-\\$2u)/2u
  9. .in +\\n(pEu
  10. .ne \\$1u
  11. ..
  12. .de PE
  13. .in -\\n(pEu
  14. ..
  15. .de D(
  16. .DS
  17. .nr VS 12p
  18. .vs 12p
  19. .I
  20. ..
  21. .de D)
  22. .DE
  23. .nr VS 18p
  24. .vs 18p
  25. .R
  26. ..
  27. .de Id
  28. .ND \\$4
  29. ..
  30. .Id $Id: rcs.ms,v 5.2 1991/01/03 10:57:28 eggert Exp $
  31. .RP
  32. .TL
  33. RCS\*-A System for Version Control
  34. .sp
  35. .AU
  36. Walter F. Tichy
  37. .AI
  38. Department of Computer Sciences
  39. Purdue University
  40. West Lafayette, Indiana 47907
  41. .sp
  42. .AB
  43. An important problem in program development and maintenance is version control,
  44. i.e., the task of keeping a software system consisting of many versions and
  45. configurations well organized.
  46. The Revision Control System (RCS)
  47. is a software tool that assists with that task.
  48. RCS manages revisions of text documents, in particular source programs,
  49. documentation, and test data.
  50. It automates the storing, retrieval, logging and identification of revisions,
  51. and it provides selection mechanisms for composing configurations.
  52. This paper introduces basic version control concepts and
  53. discusses the practice of version control
  54. using RCS.
  55. For conserving space, RCS stores deltas, i.e., differences between
  56. successive revisions.  Several delta storage methods are discussed.
  57. Usage statistics show that RCS's delta storage method is
  58. space and time efficient.
  59. The paper concludes with a detailed survey of version control tools.
  60. .sp
  61. \fBKeywords\fR: configuration management, history management,
  62. version control, revisions, deltas.
  63. .AE
  64. .FS
  65. An earlier version of this paper was published in
  66. .I "Software\*-Practice & Experience"
  67. .B 15 ,
  68. 7 (July 1985), 637-654.
  69. .FE
  70. .nr VS 18p
  71. .LP
  72. .NH
  73. Introduction
  74. .PP
  75. Version control is the task of keeping software
  76. systems consisting of many versions and configurations well organized.
  77. The Revision Control System (RCS) is a set of UNIX
  78. commands that assist with that task.
  79. .PP
  80. RCS' primary function is to manage \fIrevision groups\fR.
  81. A revision group is a set of text documents, called \fIrevisions\fR,
  82. that evolved from each other.  A new revision is
  83. created by manually editing an existing one.
  84. RCS organizes the revisions into an ancestral tree.  The initial revision
  85. is the root of the tree, and the tree edges indicate
  86. from which revision a given one evolved.
  87. Besides managing individual revision groups, RCS provides
  88. flexible selection functions for composing configurations.
  89. RCS may be combined with MAKE\u1\d,
  90. resulting in a powerful package for version control.
  91. .PP
  92. RCS also offers facilities for
  93. merging updates with customer modifications,
  94. for distributed software development, and
  95. for automatic identification.
  96. Identification is the `stamping'
  97. of revisions and configurations with unique markers.
  98. These markers are akin to serial numbers,
  99. telling software maintainers unambiguously which configuration
  100. is before them.
  101. .PP
  102. RCS is designed for both production and experimental
  103. environments.
  104. In production environments,
  105. access controls detect update conflicts and prevent overlapping changes.
  106. In experimental environments, where strong controls are
  107. counterproductive, it is possible to loosen the controls.
  108. .PP
  109. Although RCS was originally intended for programs, it is useful for any
  110. text that is revised frequently and whose previous revisions must be
  111. preserved.  RCS has been applied successfully to store the source
  112. text for drawings, VLSI layouts, documentation, specifications,
  113. test data, form letters and articles.
  114. .PP
  115. This paper discusses the practice of
  116. version control using RCS.
  117. It also introduces basic version control concepts,
  118. useful for clarifying current practice and designing similar systems.
  119. Revision groups of individual components are treated in the next three sections,
  120. and the extensions to configurations follow.
  121. Because of its size, a survey of version control tools
  122. appears at the end of the paper.
  123. .NH
  124. Getting started with RCS
  125. .PP
  126. Suppose a text file \fIf.c\fR is to be placed under control of RCS.
  127. Invoking the check-in command
  128. .D(
  129. ci  f.c
  130. .D)
  131. creates a new revision group with the contents of
  132. \fIf.c\fR as the initial
  133. revision (numbered 1.1)
  134. and stores the group into the file \fIf.c,v\fR.
  135. Unless told otherwise, the command deletes \fIf.c\fR.
  136. It also asks for a description of the group.
  137. The description should state the common purpose of all revisions in the group,
  138. and becomes part of the group's documentation.
  139. All later check-in commands will ask for a log entry,
  140. which should summarize the changes made.
  141. (The first revision is assigned a default log message,
  142. which just records the fact that it is the initial revision.)
  143. .PP
  144. Files ending in \fI,v\fR
  145. are called \fIRCS files\fR (\fIv\fR stands for \fIv\fRersions);
  146. the others are called working files.
  147. To get back the working file \fIf.c\fR in the previous example,
  148. execute the check-out command:
  149. .D(
  150. co  f.c
  151. .D)
  152. .R
  153. This command extracts the latest revision from
  154. the revision group \fIf.c,v\fR and writes
  155. it into \fIf.c\fR.
  156. The file \fIf.c\fR can now be edited and, when finished,
  157. checked back in with \fIci\fR:
  158. .D(
  159. ci  f.c
  160. .D)
  161. \fICi\fR assigns number 1.2 to
  162. the new revision.
  163. If \fIci\fR complains with the message
  164. .D(
  165. ci error: no lock set by <login>
  166. .D)
  167. then the system administrator has decided to configure RCS for a
  168. production environment by enabling the `strict locking feature'.
  169. If this feature is enabled, all RCS files are initialized
  170. such that check-in operations require a lock on the previous revision
  171. (the one from which the current one evolved).
  172. Locking prevents overlapping modifications if several people work on the same file.
  173. If locking is required, the revision should
  174. have been locked during the check-out by using
  175. the option \fI\-l\fR:
  176. .D(
  177. co  \-l  f.c
  178. .D)
  179. Of course it is too late now for the check-out with locking, because
  180. \fIf.c\fR has already been changed; checking out the file again
  181. would overwrite the modifications.
  182. (To prevent accidental overwrites, \fIco\fR senses the presence
  183. of a working file and asks whether the user really intended to overwrite it.
  184. The overwriting check-out is sometimes useful for
  185. backing up to the previous revision.)
  186. To be able to proceed with the check-in in the present case, first execute
  187. .D(
  188. rcs  \-l  f.c
  189. .D)
  190. This command retroactively locks the latest revision, unless someone
  191. else locked it in the meantime.  In this case, the two programmers
  192. involved have to negotiate whose
  193. modifications should take precedence.
  194. .PP
  195. If an RCS file is private, i.e., if only the owner of the file is expected
  196. to deposit revisions into it, the strict locking feature is unnecessary and
  197. may be disabled.
  198. If strict locking is disabled,
  199. the owner of the RCS file need not have a lock for check-in.
  200. For safety reasons, all others
  201. still do.  Turning strict locking off and on is done with the commands:
  202. .D(
  203. rcs  \-U  f.c       \fRand\fP         rcs  \-L  f.c
  204. .D)
  205. These commands enable or disable the strict locking feature for each RCS file
  206. individually.
  207. The system administrator only decides whether strict locking is
  208. enabled initially.
  209. .PP
  210. To reduce the clutter in a working directory, all RCS files can be moved
  211. to a subdirectory with the name \fIRCS\fR.
  212. RCS commands look first into that directory for RCS files.
  213. All the commands presented above work
  214. with the \fIRCS\fR subdirectory without change.\(dg
  215. .FS \(dg
  216. Pairs of RCS and working files can actually be specified in 3 ways:
  217. a) both are given, b) only the working file is given, c) only the
  218. RCS file is given.
  219. If a pair is given, both files may have arbitrary path prefixes;
  220. RCS commands pair them up intelligently.
  221. .FE
  222. .PP
  223. It may be undesirable that \fIci\fR deletes the working file.
  224. For instance, sometimes one would like to save the current revision,
  225. but continue editing.
  226. Invoking
  227. .D(
  228. ci  \-l  f.c
  229. .D)
  230. checks in \fIf.c\fR as usual, but performs an additional
  231. check-out with locking afterwards.  Thus, the working file does
  232. not disappear afte